Summary

Implements congressional district (CD) level estimation capability through a geo-stacking calibration framework with hierarchical targets database.

Key Features

Targets Database Infrastructure

• SQLite database for storing and managing calibration targets at multiple geographic levels (national, state, CD, county)
• Hierarchical validation ensuring child targets sum to parent totals
• ETL pipelines for:
  • IRS SOI data (state and county AGI distributions)
  • Medicaid enrollment by state
  • SNAP participation by state
  • Age distributions

Geo-Stacking Calibration

• Sparse matrix implementation for efficient CD-level weight calibration
• Stratified sampling approach preserving household structure
• Support for both state-only and state+CD stacking
• Comprehensive validation metrics and diagnostics

Quality Assurance

• Holdout validation framework for model evaluation
• Household-level tracing for debugging weight assignments
• Hierarchical consistency checks across geographic levels
• Weight diagnostics and distribution analysis

Developer Experience

• GEO_STACKING=true environment variable for specialized pipeline
• make data-geo target for geo-stacking workflow
• Extensive documentation in geo_stacking_calibration/ directory

Technical Details

The geo-stacking approach creates geographically-representative microdata by:

1. Stratifying CPS households by demographic/economic characteristics
2. Calibrating weights to match targets at state and CD levels simultaneously
3. Validating outputs against holdout targets and hierarchical constraints

See policyengine_us_data/datasets/cps/geo_stacking_calibration/GEO_STACKING_TECHNICAL.md for detailed methodology.

Usage

# Run geo-stacking pipeline
make data-geo

# Or directly:
GEO_STACKING=true python policyengine_us_data/datasets/cps/cps.py

Breaking Changes

None - all functionality is additive and behind feature flags.